home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_300 / 364_01 / readme.ca < prev   
Text File  |  1992-05-25  |  53KB  |  1,244 lines
  1.  
  2. C-ACROSS (version 1.02):  README.CA                Page 1
  3.  
  4. /*
  5. HEADER:         ;
  6. TITLE:          C-ACROSS;
  7. VERSION         1.02
  8.  
  9. DESCRIPTION:   "Utility for multiple module programs. Produces
  10.       Six indexes of functions, prototypes, and globals that
  11.       enable user to 'see across' modules for use in checking
  12.       and comparison.  One of these is type of hierarchical
  13.       functions list, a listing by module of functions
  14.       and calls made FROM them; another is alphabetical list
  15.       of functions and calls made TO them. Globals listed
  16.       in schematic descriptors which record all modifiers
  17.       and qualifiers and enable checking of declarators
  18.       across modules. Creates, on request, header file
  19.       consisting of prototypes constructed from function
  20.       definitions. Can list user defined types and some
  21.       preprocessor #defines. Full documentation in README.CA";
  22.  
  23. KEYWORDS:       Utility, Cross Reference, Deubgging;
  24. SYSTEM:         MS-DOS;
  25. FILENAME:       FUNC_CA.C;
  26.  
  27. WARNINGS:      "1. Assumes function definitions conform with
  28.         ANSI standards and have prototype form. See
  29.         also "Caveats and Restrictions" in README.CA.
  30.         2. Assumes syntactically correct source files.
  31.         3. Written and tested using Microsoft QuickC.
  32.         4. Copyright retained.  See Copyright
  33.         information in README.CA.";
  34.  
  35. SEE-ALSO:      EXITS_CA, FUNC_CA.C, GLOB_CA.C, IFDEF_CA.C, INTF_CA.C,
  36.            LINKL_CA.C, PARSE_CA.C, TDEF_CA.C, TYPES_CA.C, UTIL_CA.C,
  37.            UTLG_CA.C, XRF_CA.C, README.CA,
  38.            CA.H, CA.PRJ, CA.RPT, CDECL_CA.H, KEYWORDS.H;
  39. AUTHORS:       Myron Turner;
  40. COMPILERS:     Microsoft C;
  41.  
  42. */
  43.  
  44.  
  45. /***************************  C-ACROSS  ***************************/
  46.                    v. 1.02
  47.                Copyright (C) Myron Turner
  48.  
  49.               333 Bartlet Ave.
  50.               Winnipeg, Manitoba
  51.               Canada R3L 0Z9
  52.               (204) 284-8387
  53.  
  54. /*********************************************************************/
  55.  
  56.  
  57.  
  58.  
  59.  
  60. C-ACROSS (version 1.02):  README.CA                Page 2
  61.  
  62.  
  63. /*********************************************************************/
  64.  
  65.    Version 1.02 of C-ACROSS does essentially the same things as Ver 1.0.
  66.    The major exception to this statement is that it now treats function
  67.    pointers as described in II.V. and V.1.f.
  68.    It has, however, undergone many silent changes and improvements,
  69.    among them, it has:
  70.    1. Expanded treatment of typedfes;
  71.    2. Improved algorithm for treating complex declarators;
  72.    3. Improved algorithm for checking truth values of preprocessor
  73.       conditions (#if/defs);
  74.    4. Added processing of preprocessor conditionals to the parsing
  75.    of function definitions and prototypes, the absence of which in
  76.    version 1.0 was a weakness;
  77.    5. Corrected logical flaw in GLOB_CA, which by both good and
  78.    bad fortune kept things working while it concealed a number of
  79.    places where there was room for improvement;
  80.    6. Added several new switches (and deleted one);
  81.    7. Fixed small glitch which prevented the recording of certain
  82.    initialized structure/union variables.
  83.  
  84.    All in all this is a more accurate and more robust version, offering
  85.    more options.
  86.  
  87.  
  88. C-ACROSS (version 1.02):  README.CA                Page 3
  89.  
  90.  
  91.         INDEX TO HEADINGS
  92.  
  93. PAGE             HEADING
  94.  
  95.  5    I.INTRODUCTION
  96.  6    II. TYPES OF LISTS PRODUCED
  97.  6      II.1.  "I. FUNCTION DECLARATIONS AND GLOBAL VARIABLES"
  98.  7      II.2.  "II.  ALPHABETICAL INDEX OF FUNCTIONS & THEIR MODULES"
  99.  7      II.3.  "III. FUNCTIONS (LISTED BY MODULE) AND CALLS"
  100.  7      II.4.  "IV.  LIST OF FUNCTIONS AND CALLING FUNCTIONS"
  101.  7      II.5.  "V.   LISTINGS OF FUNCTION POINTERS"
  102.  7      II.6.  "VI.   GLOBAL VARIABLES LISTED ALPHABETICALLY"
  103.  7    III. INSTRUCTIONS
  104.  7      III.1. DOS INCLUDE VARIABLE
  105.  8      III.2. PATH OF C FILES
  106.  8      III.3. COMMAND LINE
  107.  10     III.4. Using a PROJECT-FILE
  108.  10     III.5. EXAMPLE COMMAND LINES
  109.  11   IV.  CAVEATS AND RESTRICTIONS
  110.  11    IV.1. PREPROCESSOR
  111.  11      IV.1.a.  Conditionals (#if. . .#ifdef..)
  112.  12     IV.1.b.  User defined types using #define.
  113.  12       IV.1.c. Using #define as compared to typedef.
  114.  12    IV.2.  FORMATTING
  115.  13    IV.3.  REPORT FILE PATHS
  116.  13    IV.4.  COMMENTS
  117.  14   IV.5. FUNCTION DEFINITIONS:  MULTIPLE LINES
  118.  14   V.  READING C-ACROSS REPORTS
  119.  14    V.1. Reading the Main Report File.
  120.  14      V.1.a.  Functions and Globals by Module.
  121.  15      V.1.b. Alphabetical listing of functions and their modules.
  122.  15      V.1.c. A listing of functions by module, in the order in whic
  123.  15      V.1.d. Alphabetical listing of functions and the functions wh
  124.  16      V.1.e. Alphabetical listing of globals, showing type, storage
  125.  20      V.1.f  The Listing and Treatment of Function Pointers.
  126.  22    V.2.  The SCRNOUT Report.
  127.  22   VI.   ERRORS
  128.  22   VII.  FILES INCLUDED ON C-ACROSS DISKS
  129.  23   VIII. COPYRIGHT
  130.  
  131.  
  132.  
  133. C-ACROSS (version 1.02):  README.CA                Page 4
  134.  
  135.  
  136.  
  137.  
  138. I.INTRODUCTION
  139.  
  140.   1. C-ACROSS is a utility for multiple module programs.  It states
  141. relationships between functions and produces annotated listings of
  142. global variables.  Its purpose is not to produce a hierarchical list
  143. of functions (although it in part does that) but to enable the programmer
  144. to see across modules in order to cross-check functions and variables.
  145. C-ACROSS reads source files and (at the user's discretion) include files.
  146. Therefore, it does not treat library functions, either standard C library
  147. functions or functions drawn from a library of the user's own. Nor, for
  148. the same reason, does it read other symbols, i.e., variables,
  149. embedded in object files.
  150.    1.a.  The term Global is used in this document to refer to all
  151.    variables which are characterized by file scope and external storage,
  152.    i.e. variables declared outside of functions and which are exported
  153.    to the linker.  This distinguishes them from static variables which
  154.    have file scope but are known only to the files in which they are
  155.    defined.  C-ACROSS does, however, list all static variables as
  156.    well as globals, even when they appear within functions.
  157.    1.b.  C-ACROSS assumes that function declarations follow the ANSI
  158.    format:
  159.         int function_1(int i, char *p)
  160.         {
  161.    It may not read the old form reliably:
  162.         int function (i, p)
  163.              int i;
  164.              char *p;
  165.          {
  166.    The reason for this is that it does not expect to find declarations
  167.    between the closed parenthesis and the opening bracket to the function.
  168.    While C-ACROSS will probably read the function names correctly,
  169.    it will treat all or some of the formal parameters as globals.
  170.    The old form will, additionally, not allow for a correct /CDECLARE
  171.    file (See III.3.b.5).
  172.  
  173.   2. Some of the kinds of problems which C-ACROSS will help resolve.
  174.     2.a. In the case of global variables the following declarations
  175.   will be accepted by the compiler and processed by the linker:
  176.  
  177.     FILE_1.C
  178.     int testvariable;
  179.     int *_far testfarintp;
  180.     int i;
  181.  
  182.     FILE_2.C
  183.     extern double testvariable;
  184.     extern int *_near testfarintp;
  185.     int i;
  186.  
  187.   "The C compiler," as Harbison and Steele point out, "cannot verify 
  188.   that declarations in different files are consistent. . . .The lint
  189.   program, usually supplied. . .in UNIX systems, can check multiple 
  190.  
  191. C-ACROSS (version 1.02):  README.CA                Page 5
  192.  
  193.   files for inconsistent declarations." (p. 94)  C-ACROSS should 
  194.   help programmers without access to a lint program check declarations
  195.   for consistency:  C-ACROSS produces fully analytical descriptions of 
  196.   both simple and complex variable declarations, listing them in table
  197.   form for ease of comparison.  (See V.1.e. for further information.)
  198.  
  199.     2.b. To facilitate function checking, C-ACROSS will produce a listing of
  200.   prototypes constructed from the actual function declarations themselves
  201.   which can then be used as a universal header file to check function calls
  202.   against the actual declaration statements.  This is good protection
  203.   against certain illegal pointer errors that are otherwise difficult
  204.   to locate.
  205.  
  206.     2.c. C-ACROSS shows at a glance which functions call every
  207.   user-def